<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Reading Mail Messages - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.mail.read.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.mail.read.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.mail.smtp-secure.html">Securing SMTP Transport</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.mail.html">Zend_Mail</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.markup.html">Zend_Markup</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.mail.read" class="section"><div class="info"><h1 class="title">Reading Mail Messages</h1></div>
    

    <p class="para">
        <span class="classname">Zend_Mail</span> can read mail messages from several local or remote mail
        storages. All of them have the same basic <acronym class="acronym">API</acronym> to count and fetch messages
        and some of them implement additional interfaces for not so common features. For a feature
        overview of the implemented storages, see the following table.
    </p>

    <table id="zend.mail.read.table-1" class="doctable table"><div class="info"><caption><b>Mail Read Feature Overview</b></caption></div>
        

        
            <thead valign="middle">
                <tr valign="middle">
                    <th>Feature</th>
                    <th>Mbox</th>
                    <th>Maildir</th>
                    <th>Pop3</th>
                    <th><b><tt>IMAP</tt></b></th>
                </tr>

            </thead>


            <tbody valign="middle" class="tbody">
                <tr valign="middle">
                    <td align="left">Storage type</td>
                    <td align="left">local</td>
                    <td align="left">local</td>
                    <td align="left">remote</td>
                    <td align="left">remote</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Fetch message</td>
                    <td align="left">Yes</td>
                    <td align="left">Yes</td>
                    <td align="left">Yes</td>
                    <td align="left">Yes</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Fetch <acronym class="acronym">MIME</acronym>-part</td>
                    <td align="left">emulated</td>
                    <td align="left">emulated</td>
                    <td align="left">emulated</td>
                    <td align="left">emulated</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Folders</td>
                    <td align="left">Yes </td>
                    <td align="left">Yes</td>
                    <td align="left">No</td>
                    <td align="left">Yes</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Create message/folder</td>
                    <td align="left">No</td>
                    <td align="left">todo</td>
                    <td align="left">No</td>
                    <td align="left">todo</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Flags</td>
                    <td align="left">No</td>
                    <td align="left">Yes</td>
                    <td align="left">No</td>
                    <td align="left">Yes</td>
                </tr>


                <tr valign="middle">
                    <td align="left">Quota</td>
                    <td align="left">No</td>
                    <td align="left">Yes</td>
                    <td align="left">No</td>
                    <td align="left">No</td>
                </tr>

            </tbody>
        
    </table>


    <div class="section" id="zend.mail.read-example"><div class="info"><h1 class="title">Simple example using Pop3</h1></div>
        

        <pre class="programlisting brush: php">
$mail = new Zend_Mail_Storage_Pop3(array(&#039;host&#039;     =&gt; &#039;localhost&#039;,
                                         &#039;user&#039;     =&gt; &#039;test&#039;,
                                         &#039;password&#039; =&gt; &#039;test&#039;));

echo $mail-&gt;countMessages() . &quot; messages found\n&quot;;
foreach ($mail as $message) {
    echo &quot;Mail from &#039;{$message-&gt;from}&#039;: {$message-&gt;subject}\n&quot;;
}
</pre>

    </div>

    <div class="section" id="zend.mail.read-open-local"><div class="info"><h1 class="title">Opening a local storage</h1></div>
        

        <p class="para">
            Mbox and Maildir are the two supported formats for local mail storages, both in their
            most simple formats.
        </p>

        <p class="para">
            If you want to read from a Mbox file you only need to give the filename to the
            constructor of <span class="classname">Zend_Mail_Storage_Mbox</span>:
        </p>

        <pre class="programlisting brush: php">
$mail = new Zend_Mail_Storage_Mbox(array(&#039;filename&#039; =&gt;
                                             &#039;/home/test/mail/inbox&#039;));
</pre>


        <p class="para">Maildir is very similar but needs a dirname:</p>

        <pre class="programlisting brush: php">
$mail = new Zend_Mail_Storage_Maildir(array(&#039;dirname&#039; =&gt;
                                                &#039;/home/test/mail/&#039;));
</pre>


        <p class="para">
            Both constructors throw a <span class="classname">Zend_Mail_Exception</span> if the storage
            can&#039;t be read.
        </p>
    </div>

    <div class="section" id="zend.mail.read-open-remote"><div class="info"><h1 class="title">Opening a remote storage</h1></div>
        

        <p class="para">
            For remote storages the two most popular protocols are supported: Pop3 and Imap. Both
            need at least a host and a user to connect and login. The default password is an empty
            string, the default port as given in the protocol <acronym class="acronym">RFC</acronym>.
        </p>

        <pre class="programlisting brush: php">
// connecting with Pop3
$mail = new Zend_Mail_Storage_Pop3(array(&#039;host&#039;     =&gt; &#039;example.com&#039;,
                                         &#039;user&#039;     =&gt; &#039;test&#039;,
                                         &#039;password&#039; =&gt; &#039;test&#039;));

// connecting with Imap
$mail = new Zend_Mail_Storage_Imap(array(&#039;host&#039;     =&gt; &#039;example.com&#039;,
                                         &#039;user&#039;     =&gt; &#039;test&#039;,
                                         &#039;password&#039; =&gt; &#039;test&#039;));

// example for a none standard port
$mail = new Zend_Mail_Storage_Pop3(array(&#039;host&#039;     =&gt; &#039;example.com&#039;,
                                         &#039;port&#039;     =&gt; 1120
                                         &#039;user&#039;     =&gt; &#039;test&#039;,
                                         &#039;password&#039; =&gt; &#039;test&#039;));
</pre>


        <p class="para">
            For both storages <acronym class="acronym">SSL</acronym> and TLS are supported. If you use
            <acronym class="acronym">SSL</acronym> the default port changes as given in the <acronym class="acronym">RFC</acronym>.
        </p>

        <pre class="programlisting brush: php">
// examples for Zend_Mail_Storage_Pop3, same works for Zend_Mail_Storage_Imap

// use SSL on different port (default is 995 for Pop3 and 993 for Imap)
$mail = new Zend_Mail_Storage_Pop3(array(&#039;host&#039;     =&gt; &#039;example.com&#039;,
                                         &#039;user&#039;     =&gt; &#039;test&#039;,
                                         &#039;password&#039; =&gt; &#039;test&#039;,
                                         &#039;ssl&#039;      =&gt; &#039;SSL&#039;));

// use TLS
$mail = new Zend_Mail_Storage_Pop3(array(&#039;host&#039;     =&gt; &#039;example.com&#039;,
                                         &#039;user&#039;     =&gt; &#039;test&#039;,
                                         &#039;password&#039; =&gt; &#039;test&#039;,
                                         &#039;ssl&#039;      =&gt; &#039;TLS&#039;));
</pre>


        <p class="para">
            Both constructors can throw <span class="classname">Zend_Mail_Exception</span> or
            <span class="classname">Zend_Mail_Protocol_Exception</span> (extends
            <span class="classname">Zend_Mail_Exception</span>), depending on the type of error.
        </p>
    </div>

    <div class="section" id="zend.mail.read-fetching"><div class="info"><h1 class="title">Fetching messages and simple methods</h1></div>
        

        <p class="para">
            Messages can be fetched after you&#039;ve opened the storage . You need the message number,
            which is a counter starting with 1 for the first message. To fetch the message, you use
            the method  <span class="methodname">getMessage()</span>:
        </p>

        <pre class="programlisting brush: php">
$message = $mail-&gt;getMessage($messageNum);
</pre>


        <p class="para">
            Array access is also supported, but this access method won&#039;t supported any additional
            parameters that could be added to  <span class="methodname">getMessage()</span>. As long as you
            don&#039;t mind, and can live with the default values, you may use:
        </p>

        <pre class="programlisting brush: php">
$message = $mail[$messageNum];
</pre>


        <p class="para">For iterating over all messages the Iterator interface is implemented:</p>

        <pre class="programlisting brush: php">
foreach ($mail as $messageNum =&gt; $message) {
    // do stuff ...
}
</pre>


        <p class="para">
            To count the messages in the storage, you can either use the method
             <span class="methodname">countMessages()</span> or use array access:
        </p>

        <pre class="programlisting brush: php">
// method
$maxMessage = $mail-&gt;countMessages();

// array access
$maxMessage = count($mail);
</pre>


        <p class="para">
            To remove a mail, you use the method  <span class="methodname">removeMessage()</span> or again
            array access:
        </p>

        <pre class="programlisting brush: php">
// method
$mail-&gt;removeMessage($messageNum);

// array access
unset($mail[$messageNum]);
</pre>

    </div>

    <div class="section" id="zend.mail.read-message"><div class="info"><h1 class="title">Working with messages</h1></div>
        

        <p class="para">
            After you fetch the messages with  <span class="methodname">getMessage()</span> you want to
            fetch headers, the content or single parts of a multipart message. All headers can be
            accessed via properties or the method  <span class="methodname">getHeader()</span> if you want
            more control or have unusual header names. The header names are lower-cased internally,
            thus the case of the header name in the mail message doesn&#039;t matter. Also headers with a
            dash can be written in camel-case. If no header is found for both notations an exception
            is thrown. To encounter this the method  <span class="methodname">headerExists()</span> can be
            used to check the existence of a header.
        </p>

        <pre class="programlisting brush: php">
// get the message object
$message = $mail-&gt;getMessage(1);

// output subject of message
echo $message-&gt;subject . &quot;\n&quot;;

// get content-type header
$type = $message-&gt;contentType;

// check if CC isset:
if( isset($message-&gt;cc) ) { // or $message-&gt;headerExists(&#039;cc&#039;);
    $cc = $message-&gt;cc;
}
</pre>


        <p class="para">
            If you have multiple headers with the same name- i.e. the Received headers- you might
            want an array instead of a string. In this case, use the
             <span class="methodname">getHeader()</span> method.
        </p>

        <pre class="programlisting brush: php">
// get header as property - the result is always a string,
// with new lines between the single occurrences in the message
$received = $message-&gt;received;

// the same via getHeader() method
$received = $message-&gt;getHeader(&#039;received&#039;, &#039;string&#039;);

// better an array with a single entry for every occurrences
$received = $message-&gt;getHeader(&#039;received&#039;, &#039;array&#039;);
foreach ($received as $line) {
    // do stuff
}

// if you don&#039;t define a format you&#039;ll get the internal representation
// (string for single headers, array for multiple)
$received = $message-&gt;getHeader(&#039;received&#039;);
if (is_string($received)) {
    // only one received header found in message
}
</pre>


        <p class="para">
            The method  <span class="methodname">getHeaders()</span> returns all headers as array with the
            lower-cased name as key and the value as and array for multiple headers or as string for
            single headers.
        </p>

        <pre class="programlisting brush: php">
// dump all headers
foreach ($message-&gt;getHeaders() as $name =&gt; $value) {
    if (is_string($value)) {
        echo &quot;$name: $value\n&quot;;
        continue;
    }
    foreach ($value as $entry) {
        echo &quot;$name: $entry\n&quot;;
    }
}
</pre>


        <p class="para">
            If you don&#039;t have a multipart message, fetching the content is easily done via
             <span class="methodname">getContent()</span>. Unlike the headers, the content is only fetched
            when needed (aka late-fetch).
        </p>

        <pre class="programlisting brush: php">
// output message content for HTML
echo &#039;&lt;pre&gt;&#039;;
echo $message-&gt;getContent();
echo &#039;&lt;/pre&gt;&#039;;
</pre>


        <p class="para">
            Checking for multipart messages is done with the method
             <span class="methodname">isMultipart()</span>. If you have multipart message you can get an
            instance of <span class="classname">Zend_Mail_Part</span> with the method
             <span class="methodname">getPart()</span>. <span class="classname">Zend_Mail_Part</span> is the base
            class of <span class="classname">Zend_Mail_Message</span>, so you have the same methods:
             <span class="methodname">getHeader()</span>,  <span class="methodname">getHeaders()</span>,
             <span class="methodname">getContent()</span>,  <span class="methodname">getPart()</span>,
             <span class="methodname">isMultipart()</span> and the properties for headers.
        </p>

        <pre class="programlisting brush: php">
// get the first none multipart part
$part = $message;
while ($part-&gt;isMultipart()) {
    $part = $message-&gt;getPart(1);
}
echo &#039;Type of this part is &#039; . strtok($part-&gt;contentType, &#039;;&#039;) . &quot;\n&quot;;
echo &quot;Content:\n&quot;;
echo $part-&gt;getContent();
</pre>


        <p class="para">
            <span class="classname">Zend_Mail_Part</span> also implements
            <span class="classname">RecursiveIterator</span>, which makes it easy to scan through all
            parts. And for easy output, it also implements the magic method
             <span class="methodname">__toString()</span>, which returns the content.
        </p>

        <pre class="programlisting brush: php">
// output first text/plain part
$foundPart = null;
foreach (new RecursiveIteratorIterator($mail-&gt;getMessage(1)) as $part) {
    try {
        if (strtok($part-&gt;contentType, &#039;;&#039;) == &#039;text/plain&#039;) {
            $foundPart = $part;
            break;
        }
    } catch (Zend_Mail_Exception $e) {
        // ignore
    }
}
if (!$foundPart) {
    echo &#039;no plain text part found&#039;;
} else {
    echo &quot;plain text part: \n&quot; . $foundPart;
}
</pre>

    </div>

    <div class="section" id="zend.mail.read-flags"><div class="info"><h1 class="title">Checking for flags</h1></div>
        

        <p class="para">
            Maildir and IMAP support storing flags. The class
            <span class="classname">Zend_Mail_Storage</span> has constants for all known maildir and IMAP
            system flags, named <span class="classname">Zend_Mail_Storage::FLAG_&lt;flagname&gt;</span>. To
            check for flags <span class="classname">Zend_Mail_Message</span> has a method called
             <span class="methodname">hasFlag()</span>. With  <span class="methodname">getFlags()</span> you&#039;ll get
            all set flags.
        </p>

        <pre class="programlisting brush: php">
// find unread messages
echo &quot;Unread mails:\n&quot;;
foreach ($mail as $message) {
    if ($message-&gt;hasFlag(Zend_Mail_Storage::FLAG_SEEN)) {
        continue;
    }
    // mark recent/new mails
    if ($message-&gt;hasFlag(Zend_Mail_Storage::FLAG_RECENT)) {
        echo &#039;! &#039;;
    } else {
        echo &#039;  &#039;;
    }
    echo $message-&gt;subject . &quot;\n&quot;;
}

// check for known flags
$flags = $message-&gt;getFlags();
echo &quot;Message is flagged as: &quot;;
foreach ($flags as $flag) {
    switch ($flag) {
        case Zend_Mail_Storage::FLAG_ANSWERED:
            echo &#039;Answered &#039;;
            break;
        case Zend_Mail_Storage::FLAG_FLAGGED:
            echo &#039;Flagged &#039;;
            break;

        // ...
        // check for other flags
        // ...

        default:
            echo $flag . &#039;(unknown flag) &#039;;
    }
}
</pre>


        <p class="para">
            As IMAP allows user or client defined flags, you could get flags that don&#039;t have a
            constant in <span class="classname">Zend_Mail_Storage</span>. Instead, they are returned as
            strings and can be checked the same way with  <span class="methodname">hasFlag()</span>.
        </p>

        <pre class="programlisting brush: php">
// check message for client defined flags $IsSpam, $SpamTested
if (!$message-&gt;hasFlag(&#039;$SpamTested&#039;)) {
    echo &#039;message has not been tested for spam&#039;;
} else if ($message-&gt;hasFlag(&#039;$IsSpam&#039;)) {
    echo &#039;this message is spam&#039;;
} else {
    echo &#039;this message is ham&#039;;
}
</pre>

    </div>

    <div class="section" id="zend.mail.read-folders"><div class="info"><h1 class="title">Using folders</h1></div>
        

        <p class="para">
            All storages, except Pop3, support folders, also called mailboxes. The interface
            implemented by all storages supporting folders is called
            <span class="classname">Zend_Mail_Storage_Folder_Interface</span>. Also all of these classes
            have an additional optional parameter called <span class="property">folder</span>, which is the
            folder selected after login, in the constructor.
        </p>

        <p class="para">
            For the local storages you need to use separate classes called
            <span class="classname">Zend_Mail_Storage_Folder_Mbox</span> or
            <span class="classname">Zend_Mail_Storage_Folder_Maildir</span>. Both need one parameter called
            <span class="property">dirname</span> with the name of the base dir. The format for maildir is as
            defined in maildir++ (with a dot as default delimiter), Mbox is a directory hierarchy
            with Mbox files. If you don&#039;t have a Mbox file called INBOX in your Mbox base dir you
            need to set another folder in the constructor.
        </p>

        <p class="para">
            <span class="classname">Zend_Mail_Storage_Imap</span> already supports folders by default.
            Examples for opening these storages:
        </p>

        <pre class="programlisting brush: php">
// mbox with folders
$mail = new Zend_Mail_Storage_Folder_Mbox(array(&#039;dirname&#039; =&gt;
                                                    &#039;/home/test/mail/&#039;));

// mbox with a default folder not called INBOX, also works
// with Zend_Mail_Storage_Folder_Maildir and Zend_Mail_Storage_Imap
$mail = new Zend_Mail_Storage_Folder_Mbox(array(&#039;dirname&#039; =&gt;
                                                    &#039;/home/test/mail/&#039;,
                                                &#039;folder&#039;  =&gt;
                                                    &#039;Archive&#039;));

// maildir with folders
$mail = new Zend_Mail_Storage_Folder_Maildir(array(&#039;dirname&#039; =&gt;
                                                       &#039;/home/test/mail/&#039;));

// maildir with colon as delimiter, as suggested in Maildir++
$mail = new Zend_Mail_Storage_Folder_Maildir(array(&#039;dirname&#039; =&gt;
                                                       &#039;/home/test/mail/&#039;,
                                                   &#039;delim&#039;   =&gt; &#039;:&#039;));

// imap is the same with and without folders
$mail = new Zend_Mail_Storage_Imap(array(&#039;host&#039;     =&gt; &#039;example.com&#039;,
                                         &#039;user&#039;     =&gt; &#039;test&#039;,
                                         &#039;password&#039; =&gt; &#039;test&#039;));
</pre>


        <p class="para">
            With the method getFolders($root = null) you can get the folder hierarchy starting with
            the root folder or the given folder. It&#039;s returned as an instance of
            <span class="classname">Zend_Mail_Storage_Folder</span>, which implements
            <span class="classname">RecursiveIterator</span> and all children are also instances of
            <span class="classname">Zend_Mail_Storage_Folder</span>. Each of these instances has a local and
            a global name returned by the methods  <span class="methodname">getLocalName()</span> and
             <span class="methodname">getGlobalName()</span>. The global name is the absolute name from the
            root folder (including delimiters), the local name is the name in the parent folder.
        </p>

        <table id="zend.mail.read-folders.table-1" class="doctable table"><div class="info"><caption><b>Mail Folder Names</b></caption></div>
            

            
                <thead valign="middle">
                    <tr valign="middle">
                        <th>Global Name</th>
                        <th>Local Name</th>
                    </tr>

                </thead>


                <tbody valign="middle" class="tbody">
                    <tr valign="middle">
                        <td align="left">/INBOX</td>
                        <td align="left">INBOX</td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">/Archive/2005</td>
                        <td align="left">2005</td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">List.ZF.General</td>
                        <td align="left">General</td>
                    </tr>

                </tbody>
            
        </table>


        <p class="para">
            If you use the iterator, the key of the current element is the local name. The global
            name is also returned by the magic method  <span class="methodname">__toString()</span>. Some
            folders may not be selectable, which means they can&#039;t store messages and selecting them
            results in an error. This can be checked with the method
             <span class="methodname">isSelectable()</span>. So it&#039;s very easy to output the whole tree in a
            view:
        </p>

        <pre class="programlisting brush: php">
$folders = new RecursiveIteratorIterator($this-&gt;mail-&gt;getFolders(),
                                         RecursiveIteratorIterator::SELF_FIRST);
echo &#039;&lt;select name=&quot;folder&quot;&gt;&#039;;
foreach ($folders as $localName =&gt; $folder) {
    $localName = str_pad(&#039;&#039;, $folders-&gt;getDepth(), &#039;-&#039;, STR_PAD_LEFT) .
                 $localName;
    echo &#039;&lt;option&#039;;
    if (!$folder-&gt;isSelectable()) {
        echo &#039; disabled=&quot;disabled&quot;&#039;;
    }
    echo &#039; value=&quot;&#039; . htmlspecialchars($folder) . &#039;&quot;&gt;&#039;
        . htmlspecialchars($localName) . &#039;&lt;/option&gt;&#039;;
}
echo &#039;&lt;/select&gt;&#039;;
</pre>


        <p class="para">
            The current selected folder is returned by the method
             <span class="methodname">getCurrentFolder()</span>. Changing the folder is done with the
            method  <span class="methodname">selectFolder()</span>, which needs the global name as
            parameter. If you want to avoid to write delimiters you can also use the properties of a
            <span class="classname">Zend_Mail_Storage_Folder</span> instance:
        </p>

        <pre class="programlisting brush: php">
// depending on your mail storage and its settings $rootFolder-&gt;Archive-&gt;2005
// is the same as:
//   /Archive/2005
//  Archive:2005
//  INBOX.Archive.2005
//  ...
$folder = $mail-&gt;getFolders()-&gt;Archive-&gt;2005;
echo &#039;Last folder was &#039;
   . $mail-&gt;getCurrentFolder()
   . &quot;new folder is $folder\n&quot;;
$mail-&gt;selectFolder($folder);
</pre>

    </div>

    <div class="section" id="zend.mail.read-advanced"><div class="info"><h1 class="title">Advanced Use</h1></div>
        

        <div class="section" id="zend.mail.read-advanced.noop"><div class="info"><h1 class="title">Using NOOP</h1></div>
            

            <p class="para">
                If you&#039;re using a remote storage and have some long tasks you might need to keep
                the connection alive via noop:
            </p>

            <pre class="programlisting brush: php">
foreach ($mail as $message) {

    // do some calculations ...

    $mail-&gt;noop(); // keep alive

    // do something else ...

    $mail-&gt;noop(); // keep alive
}
</pre>

        </div>

        <div class="section" id="zend.mail.read-advanced.caching"><div class="info"><h1 class="title">Caching instances</h1></div>
            

            <p class="para">
                <span class="classname">Zend_Mail_Storage_Mbox</span>,
                <span class="classname">Zend_Mail_Storage_Folder_Mbox</span>,
                <span class="classname">Zend_Mail_Storage_Maildir</span> and
                <span class="classname">Zend_Mail_Storage_Folder_Maildir</span> implement the magic methods
                 <span class="methodname">__sleep()</span> and  <span class="methodname">__wakeup()</span>, which
                means they are serializable. This avoids parsing the files or directory tree more
                than once. The disadvantage is that your Mbox or Maildir storage should not change.
                Some easy checks may be done, like reparsing the current Mbox file if the
                modification time changes, or reparsing the folder structure if a folder has
                vanished (which still results in an error, but you can search for another folder
                afterwards). It&#039;s better if you have something like a signal file for changes and
                check it before using the cached instance.
            </p>

            <pre class="programlisting brush: php">
// there&#039;s no specific cache handler/class used here,
// change the code to match your cache handler
$signal_file = &#039;/home/test/.mail.last_change&#039;;
$mbox_basedir = &#039;/home/test/mail/&#039;;
$cache_id = &#039;example mail cache &#039; . $mbox_basedir . $signal_file;

$cache = new Your_Cache_Class();
if (!$cache-&gt;isCached($cache_id) ||
    filemtime($signal_file) &gt; $cache-&gt;getMTime($cache_id)) {
    $mail = new Zend_Mail_Storage_Folder_Pop3(array(&#039;dirname&#039; =&gt;
                                                        $mbox_basedir));
} else {
    $mail = $cache-&gt;get($cache_id);
}

// do stuff ...

$cache-&gt;set($cache_id, $mail);
</pre>

        </div>

        <div class="section" id="zend.mail.read-advanced.extending"><div class="info"><h1 class="title">Extending Protocol Classes</h1></div>
            

            <p class="para">
                Remote storages use two classes:
                <span class="classname">Zend_Mail_Storage_&lt;Name&gt;</span> and
                <span class="classname">Zend_Mail_Protocol_&lt;Name&gt;</span>. The protocol class
                translates the protocol commands and responses from and to <acronym class="acronym">PHP</acronym>,
                like methods for the commands or variables with different structures for data.
                The other/main class implements the common interface.
            </p>

            <p class="para">
                If you need additional protocol features, you can extend the protocol class and use
                it in the constructor of the main class. As an example, assume we need to knock
                different ports before we can connect to POP3.
            </p>

            <pre class="programlisting brush: php">
class Example_Mail_Exception extends Zend_Mail_Exception
{
}

class Example_Mail_Protocol_Exception extends Zend_Mail_Protocol_Exception
{
}

class Example_Mail_Protocol_Pop3_Knock extends Zend_Mail_Protocol_Pop3
{
    private $host, $port;

    public function __construct($host, $port = null)
    {
        // no auto connect in this class
        $this-&gt;host = $host;
        $this-&gt;port = $port;
    }

    public function knock($port)
    {
        $sock = @fsockopen($this-&gt;host, $port);
        if ($sock) {
            fclose($sock);
        }
    }

    public function connect($host = null, $port = null, $ssl = false)
    {
        if ($host === null) {
            $host = $this-&gt;host;
        }
        if ($port === null) {
            $port = $this-&gt;port;
        }
        parent::connect($host, $port);
    }
}

class Example_Mail_Pop3_Knock extends Zend_Mail_Storage_Pop3
{
    public function __construct(array $params)
    {
        // ... check $params here! ...
        $protocol = new Example_Mail_Protocol_Pop3_Knock($params[&#039;host&#039;]);

        // do our &quot;special&quot; thing
        foreach ((array)$params[&#039;knock_ports&#039;] as $port) {
            $protocol-&gt;knock($port);
        }

        // get to correct state
        $protocol-&gt;connect($params[&#039;host&#039;], $params[&#039;port&#039;]);
        $protocol-&gt;login($params[&#039;user&#039;], $params[&#039;password&#039;]);

        // initialize parent
        parent::__construct($protocol);
    }
}

$mail = new Example_Mail_Pop3_Knock(array(&#039;host&#039;        =&gt; &#039;localhost&#039;,
                                          &#039;user&#039;        =&gt; &#039;test&#039;,
                                          &#039;password&#039;    =&gt; &#039;test&#039;,
                                          &#039;knock_ports&#039; =&gt;
                                              array(1101, 1105, 1111)));
</pre>


            <p class="para">
                As you see, we always assume we&#039;re connected, logged in and, if supported, a folder
                is selected in the constructor of the main class. Thus if you assign your own
                protocol class, you always need to make sure that&#039;s done or the next method will
                fail if the server doesn&#039;t allow it in the current state.
            </p>
        </div>

        <div class="section" id="zend.mail.read-advanced.quota"><div class="info"><h1 class="title">Using Quota (since 1.5)</h1></div>
            

            <p class="para">
                <span class="classname">Zend_Mail_Storage_Writable_Maildir</span> has support for Maildir++
                quotas. It&#039;s disabled by default, but it&#039;s possible to use it manually, if the
                automatic checks are not desired (this means
                 <span class="methodname">appendMessage()</span>,  <span class="methodname">removeMessage()</span>
                and  <span class="methodname">copyMessage()</span> do no checks and do not add entries to
                the maildirsize file). If enabled, an exception is thrown if you try to write to the
                maildir and it&#039;s already over quota.
            </p>

            <p class="para">
                There are three methods used for quotas:  <span class="methodname">getQuota()</span>,
                 <span class="methodname">setQuota()</span> and  <span class="methodname">checkQuota()</span>:
            </p>

            <pre class="programlisting brush: php">
$mail = new Zend_Mail_Storage_Writable_Maildir(array(&#039;dirname&#039; =&gt;
                                                   &#039;/home/test/mail/&#039;));
$mail-&gt;setQuota(true); // true to enable, false to disable
echo &#039;Quota check is now &#039;, $mail-&gt;getQuota() ? &#039;enabled&#039; : &#039;disabled&#039;, &quot;\n&quot;;
// check quota can be used even if quota checks are disabled
echo &#039;You are &#039;, $mail-&gt;checkQuota() ? &#039;over quota&#039; : &#039;not over quota&#039;, &quot;\n&quot;;
</pre>


            <p class="para">
                 <span class="methodname">checkQuota()</span> can also return a more detailed response:
            </p>

            <pre class="programlisting brush: php">
$quota = $mail-&gt;checkQuota(true);
echo &#039;You are &#039;, $quota[&#039;over_quota&#039;] ? &#039;over quota&#039; : &#039;not over quota&#039;, &quot;\n&quot;;
echo &#039;You have &#039;,
     $quota[&#039;count&#039;],
     &#039; of &#039;,
     $quota[&#039;quota&#039;][&#039;count&#039;],
     &#039; messages and use &#039;;
echo $quota[&#039;size&#039;], &#039; of &#039;, $quota[&#039;quota&#039;][&#039;size&#039;], &#039; octets&#039;;
</pre>


            <p class="para">
                If you want to specify your own quota instead of using the one specified in the
                maildirsize file you can do with  <span class="methodname">setQuota()</span>:
            </p>

            <pre class="programlisting brush: php">
// message count and octet size supported, order does matter
$quota = $mail-&gt;setQuota(array(&#039;size&#039; =&gt; 10000, &#039;count&#039; =&gt; 100));
</pre>


            <p class="para">
                To add your own quota checks use single letters as keys, and they will be preserved
                (but obviously not checked). It&#039;s also possible to extend
                <span class="classname">Zend_Mail_Storage_Writable_Maildir</span> to define your own quota
                only if the maildirsize file is missing (which can happen in Maildir++):
            </p>

            <pre class="programlisting brush: php">
class Example_Mail_Storage_Maildir extends Zend_Mail_Storage_Writable_Maildir {
    // getQuota is called with $fromStorage = true by quota checks
    public function getQuota($fromStorage = false) {
        try {
            return parent::getQuota($fromStorage);
        } catch (Zend_Mail_Storage_Exception $e) {
            if (!$fromStorage) {
                // unknown error:
                throw $e;
            }
            // maildirsize file must be missing

            list($count, $size) = get_quota_from_somewhere_else();
            return array(&#039;count&#039; =&gt; $count, &#039;size&#039; =&gt; $size);
        }
    }
}
</pre>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.mail.smtp-secure.html">Securing SMTP Transport</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.mail.html">Zend_Mail</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.markup.html">Zend_Markup</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.mail.html">Zend_Mail</a></li>
  <li><a href="zend.mail.introduction.html">Introduction</a></li>
  <li><a href="zend.mail.sending.html">Sending via SMTP</a></li>
  <li><a href="zend.mail.multiple-emails.html">Sending Multiple Mails per SMTP Connection</a></li>
  <li><a href="zend.mail.different-transports.html">Using Different Transports</a></li>
  <li><a href="zend.mail.html-mails.html">HTML E-Mail</a></li>
  <li><a href="zend.mail.attachments.html">Attachments</a></li>
  <li><a href="zend.mail.adding-recipients.html">Adding Recipients</a></li>
  <li><a href="zend.mail.boundary.html">Controlling the MIME Boundary</a></li>
  <li><a href="zend.mail.additional-headers.html">Additional Headers</a></li>
  <li><a href="zend.mail.character-sets.html">Character Sets</a></li>
  <li><a href="zend.mail.encoding.html">Encoding</a></li>
  <li><a href="zend.mail.smtp-authentication.html">SMTP Authentication</a></li>
  <li><a href="zend.mail.smtp-secure.html">Securing SMTP Transport</a></li>
  <li class="active"><a href="zend.mail.read.html">Reading Mail Messages</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>